Back to Contents        Previous        Next

25. Dragging icons

We have already experienced two special types of icon dragging with Dr Wimp i.e. saving data by dragging the drag% icon of a ‘Save box’ (Section 2.7) and dragging Sliders (Section 2.16).

Dr Wimp has facilities to manage simple dragging of all other icons - provided that they have been defined as ‘draggable’ in their definition.

The user can also define his/her own drag-box, independent of icons.

Dragging icons
Once a draggable icon is displayed in a window of your application, it needs only one simple item of preparation before it can be dragged around the window by holding down either the <select> or <adjust> mouse button whilst moving the mouse.

In the skeleton !RunImage is the user-function:

DEF FNuser_dragicon(window%,icon%,button%)
=0

This user-function is automatically called whenever the user starts a drag action on an icon which has been defined as draggable i.e. when either the <select> or <adjust> button is pressed and held down over such an icon. As can be seen, the default return is 0 and all you have to do is set the return value to 1 when you want dragging to actually occur.

As usual, the parameters tell you which window/icon pair is involved and which button has been used. (Note that it will be the usual 4 or 1 for <select> or <adjust> respectively.) So, a typical simple coding might be:

DEF FNuser_dragicon(window%,icon%,button%)
LOCAL return%
return%=0
CASE window% OF
WHEN main%
         CASE icon% OF
         WHEN 6
         return%=1
ENDCASE
ENDCASE
=return%

This would mean that dragging would only actually begin to occur when the user seeks to drag Icon 6 in window main%. Any attempt to drag any other draggable icon will be ignored. Clearly you can easily make the coding respond to other possibilities.

When dragging takes place it will actually drag a rectangle (the ‘drag box’) the same size as the icon and with a ‘rotating dash’ border. When you end the drag the rectangle will simply disappear and, at the moment, nothing else will happen.


To allow the programmer to make something happen Dr Wimp provides three user-functions:

PROCuser_seticondragbounds()
PROCuser_draggingicon()
PROCuser_endicondrag()

and they come into play before, during and at the end of the drag, respectively, as follows:


DEF PROCuser_seticondragbounds(startwindow%,dragicon%, dragbutton%,startmousex%,startmousey%,RETURN boundsminx%, RETURN boundsminy%,RETURN boundsmaxx%,RETURN boundsmaxy%)
ENDPROC

This user-function is automatically called from within the DrWimp library at the start of an icon drag and its purpose is to allow the programmer to set the limits of the area in which the dragging can take place.

The passed parameters are: startwindow% - the handle of the window% which owns the dragged icon; dragicon% - the handle of the dragged icon; dragbutton% - the button state whilst dragging i.e. either 4 for <select-drag> or 1 for <adjust­drag>; startmousex% and startmousey% - the mouse pointer coordinates at the start of the drag, in screen OS values i.e. referred to bottom left corner of screen; and finally boundsminx%, boundsminy%, boundsmaxx% & boundsmaxy% are the required dragging limits, in screen OS values.


You will see that the last four parameters are RETURN parameters (remember to keep a space between each RETURN and its variable) so this gives you the opportunity to set your required values within this user-function - using the other parameters as and if you wish to ‘filter’ the conditions more precisely.


If you choose to leave this user-function empty the dragging will be confined to the area of the visible window in which the dragged icon starts, but by using this user-function the limits can be changed so that the drag box can be dragged anywhere on the screen.


DEF PROCuser_draggingicon(startwindow%,dragicon%,dragbutton%, startmousex%,startmousey%,mousex%,mousey%,
overwindow%,overicon%,dragboxminx%,dragboxminy%,
dragboxmaxx%,dragboxmaxy%)
ENDPROC

This user-function is called repeatedly by the Wimp whilst the icon is being dragged and provides a means for the programmer to take action during the drag, if required.

The parameters startwindow%, dragicon%, dragbutton%, startmousex% and startmousey% are the same as in the previous user-function above, but mousex% and mousey% are now the instantaneous mouse pointer screen OS coordinates during the drag. The parameters overwindow% and overicon% are the handles of the window and icon which the pointer is currently over during the drag. (Values of -1 are given when the pointer is not over a window/icon.)

The parameters dragboxminx%, dragboxminy%, dragboxmaxx% and dragboxmaxy% are the instantaneous screen OS coordinates of the ‘drag box’.

Typical uses for this user-function might be to display the corrdinates of the current mouse pointer position, or to trigger certain action when the drag passes over a specific window/icon combination.



DEF PROCuser_endicondrag(startwindow%,dragicon%,dragbutton%, startmousex%,startmousey%,dragboxminx%,dragboxminy%, dragboxmaxx%,dragboxmaxy%,endwindow%,endicon%,endmousex%, endmousey%)
ENDPROC


As its name suggests, this user-function is called automatically when the drag ends - passing to the programmer the end-of-drag values of the various parameters which are, by now, self-explanatory. The wide variety of parameters gives the programmer many opportunities to decide what action to take when the drag ends.

One such action may be to copy (or move) the icon and Dr Wimp provides Elixir_02 (see Section 2.36) specifically for this. It allows an exact copy of the dragged icon to be created at the place where the drag ends - with the option to delete the original icon i.e. the dragged icon.



User-defined drag-boxes
The user can also define and start to drag any drag-box - independent of icons - by using the simple facility provided in Elixir_04 - see Section 2.36.

However it is worth noting here that, for convenience, Elixir_04 also uses:

PROCuser_seticondragbounds()
PROCuser_draggingicon()
PROCuser_endicondrag()

as described above, but in this case the value of dragicon% will always be -1.








Top of page        Back to Contents        Previous        Next